中文 | English

当你需要对 providers、策略和集成进行更细粒度的控制时，请使用这些选项。若想快速起步，请参见 Config basics。

关于项目级指导、可复用能力、自定义斜杠命令、subagent 工作流和集成的背景，请参见 Customization。关于配置键，请参见 Configuration Reference。

Profiles 让你可以保存具名的配置值集合，并从 CLI 中切换它们。

Profiles 属于实验性功能，未来版本中可能会变化或被移除。

Codex IDE 扩展当前尚不支持 Profiles。

在 config.toml 中的 [profiles.<name>] 下定义 profiles，然后运行 codex --profile <name>：

model = "gpt-5.4"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"

如果想让某个 profile 成为默认值，可在 config.toml 顶层添加 profile = "deep-review"。除非你在命令行里覆盖它，否则 Codex 会加载该 profile。

Profiles 也可以覆盖 model_catalog_json。如果顶层和所选 profile 都设置了 model_catalog_json，Codex 会优先使用 profile 中的值。

从 CLI 做一次性覆盖

除了编辑 ~/.codex/config.toml，你还可以从 CLI 为单次运行覆盖配置：

• 如果存在专用 flag，优先使用专用 flag（例如 --model）。
• 当你需要覆盖任意键时，使用 -c / --config。

示例：

# Dedicated flag
codex --model gpt-5.4

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

说明：

• 键可以使用点号记法来设置嵌套值（例如 mcp_servers.context7.enabled=false）。
• --config 的值按 TOML 解析。如有疑问，请给该值加上引号，以避免 shell 按空格拆分。
• 如果该值无法按 TOML 解析，Codex 会把它当作字符串处理。

配置和状态位置

Codex 会把本地状态保存在 CODEX_HOME 下（默认是 ~/.codex）。

你常见到的文件包括：

• config.toml（你的本地配置）
• auth.json（如果你使用基于文件的凭据存储）或操作系统的 keychain/keyring
• history.jsonl（如果启用了历史持久化）
• 其他按用户存放的状态，例如日志和缓存

关于认证细节（包括凭据存储模式），请参见 Authentication。关于完整配置键列表，请参见 Configuration Reference。

关于检入仓库或系统路径中的共享默认值、规则和 skills，请参见 Team Config。

如果你只是想让内置 OpenAI provider 指向一个 LLM proxy、router 或启用了数据驻留的项目，请在 config.toml 中设置 openai_base_url，而不是定义新的 provider。这样会修改内置 openai provider 的 base URL，而不需要额外的 model_providers.<id> 条目。

openai_base_url = "https://us.api.openai.com/v1"

项目配置文件（.codex/config.toml）

除了用户级配置外，Codex 还会读取仓库内 .codex/config.toml 文件里的项目级覆盖项。Codex 会从项目根目录一路走到当前工作目录，并加载沿途找到的每一个 .codex/config.toml。如果多个文件定义了同一个键，则离当前工作目录最近的文件优先。

出于安全考虑，Codex 只会在项目受信时加载项目级配置文件。如果项目不受信，Codex 会忽略项目中的 .codex/config.toml 文件。

项目配置中的相对路径（例如 model_instructions_file）是相对于包含该 config.toml 的 .codex/ 文件夹来解析的。

Hooks（实验性）

Codex 也可以从与活动配置层相邻的 hooks.json 文件中加载生命周期 hooks。

实践中，最有用的两个位置通常是：

• ~/.codex/hooks.json
• <repo>/.codex/hooks.json

通过下面的配置打开 hooks：

[features]
codex_hooks = true

关于当前事件列表、输入字段、输出行为和限制，请参见 Hooks。

Agent roles（config.toml 中的 [agents]）

关于 subagent 角色配置（config.toml 中的 [agents]），请参见 Subagents。

项目根检测

Codex 会通过从工作目录向上遍历直到遇到项目根的方式，发现项目配置（例如 .codex/ 配置层与 AGENTS.md）。

默认情况下，Codex 会把包含 .git 的目录视为项目根。如果想自定义这一行为，请在 config.toml 中设置 project_root_markers：

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

将 project_root_markers = [] 设为空数组，可以跳过父目录搜索，并把当前工作目录直接视为项目根。

自定义 model providers

Model provider 定义了 Codex 如何连接到模型（base URL、wire API 以及可选的 HTTP headers）。

定义额外 providers，并把 model_provider 指向它们：

model = "gpt-5.4"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

在需要时添加请求头：

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

OSS mode（本地 providers）

当你传入 --oss 时，Codex 可以运行在本地“开源” provider 之上（例如 Ollama 或 LM Studio）。如果你传入 --oss 却未指定 provider，Codex 会使用 oss_provider 作为默认值。

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Azure provider 与按 provider 调优

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"

[model_providers.openai]
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

使用数据驻留的 ChatGPT 客户

启用了 data residency 的项目，可以创建一个 model provider，通过设置 正确的前缀 来更新 base_url。

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

模型推理、verbosity 与限制

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

model_verbosity 只适用于使用 Responses API 的 providers。基于 Chat Completions 的 providers 会忽略该设置。

审批策略与沙箱模式

选择审批严格程度（影响 Codex 何时暂停）以及沙箱级别（影响文件/网络访问）。

关于编辑 config.toml 时需要牢记的运行细节，请参见 Common sandbox and approval combinations、Protected paths in writable roots 和 Network access。

你也可以使用细粒度审批策略（approval_policy = { granular = { ... } }）来允许或自动拒绝单独的 prompt 类别。当你希望对某些情况仍然使用正常的交互式审批，但希望其他情况（例如 request_permissions 或 skill-script prompts）默认关闭时，这会很有用。

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

需要完整键列表（包括 profile 作用域覆盖项和 requirements 约束）？请参见 Configuration Reference 与 Managed configuration。

在 workspace-write 模式下，有些环境会让 .git/ 和 .codex/ 保持只读，即便工作区其余部分可写也是如此。这就是为什么像 git commit 这样的命令仍可能需要在沙箱外获得审批。如果你想让 Codex 跳过特定命令（例如阻止 git commit 在沙箱外运行），请使用 rules。

完全关闭沙箱（仅在你的环境已经隔离进程时使用）：

sandbox_mode = "danger-full-access"

Shell environment policy

shell_environment_policy 控制 Codex 会把哪些环境变量传递给它启动的任意子进程（例如运行模型提出的 tool-command 时）。你可以从干净起点（inherit = "none"）或裁剪过的集合（inherit = "core"）开始，再分层叠加 excludes、includes 和 overrides，以避免泄露 secrets，同时仍提供任务所需的路径、keys 或 flags。

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]

这些模式是大小写不敏感的 glob（*、?、[A-Z]）；ignore_default_excludes = false 会在你的 includes/excludes 生效之前，先保留自动的 KEY/SECRET/TOKEN 过滤器。

MCP servers

关于配置细节，请参见专门的 MCP 文档。

可观测性与遥测

启用 OpenTelemetry（OTel）日志导出，以跟踪 Codex 运行（API requests、SSE/events、prompts、tool approvals/results）。默认关闭；通过 [otel] 显式启用：

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

选择一个 exporter：

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

如果 exporter = "none"，Codex 会记录事件，但不会发送任何内容。Exporters 会异步批量发送，并在关闭时 flush。事件元数据包括服务名、CLI 版本、环境标签、conversation id、model、sandbox/approval settings，以及每个事件自身的字段（见 Config Reference）。

会发出什么

Codex 会为运行和工具使用发出结构化日志事件。具有代表性的事件类型包括：

• codex.conversation_starts（model、reasoning settings、sandbox/approval policy）
• codex.api_request（attempt、status/success、duration 与 error details）
• codex.sse_event（stream event kind、success/failure、duration，以及在 response.completed 上的 token counts）
• codex.websocket_request 与 codex.websocket_event（request duration 以及每条消息的 kind/success/error）
• codex.user_prompt（长度；除非显式启用，否则内容会被脱敏）
• codex.tool_decision（是否批准/拒绝，以及该决策来自 config 还是 user）
• codex.tool_result（duration、success、output snippet）

发出的 OTel 指标

当 OTel 指标流水线启用时，Codex 会为 API、stream 和 tool 活动发出计数器与时长直方图。

下面每个指标还会附带默认元数据标签：auth_mode、originator、session_source、model 和 app.version。

指标	类型	字段	描述
codex.api_request	counter	status, success	按 HTTP 状态及成功/失败统计 API 请求数。
codex.api_request.duration_ms	histogram	status, success	API 请求时长（毫秒）。
codex.sse_event	counter	kind, success	按事件种类与成功/失败统计 SSE 事件数。
codex.sse_event.duration_ms	histogram	kind, success	SSE 事件处理时长（毫秒）。
codex.websocket.request	counter	success	按成功/失败统计 WebSocket 请求数。
codex.websocket.request.duration_ms	histogram	success	WebSocket 请求时长（毫秒）。
codex.websocket.event	counter	kind, success	按类型与成功/失败统计 WebSocket 消息/事件数。
codex.websocket.event.duration_ms	histogram	kind, success	WebSocket 消息/事件处理时长（毫秒）。
codex.tool.call	counter	tool, success	按工具名与结果统计工具调用次数。
codex.tool.call.duration_ms	histogram	tool, success	按工具名与结果统计工具执行时长（毫秒）。

关于 telemetry 的安全与隐私指引，请参见 Security。

Metrics

默认情况下，Codex 会定期向 OpenAI 回传少量匿名使用与健康数据。这有助于发现 Codex 何时工作不正常，也能反映哪些功能和配置选项正在被使用，从而让 Codex 团队聚焦最重要的事情。这些 metrics 不包含任何 personally identifiable information（PII）。Metrics 收集与 OTel 日志/trace 导出相互独立。

如果你想在一台机器上的所有 Codex 界面中完全关闭 metrics 收集，请在配置里设置 analytics 标志：

[analytics]
enabled = false

每个 metric 都包含其自身字段以及下面的默认上下文字段。

默认上下文字段（适用于每个事件/metric）

• auth_mode：swic | api | unknown。
• model：所使用模型的名称。
• app.version：Codex 版本。

Metrics 目录

每个 metric 都包含必需字段以及上面的默认上下文字段。每个 metric 名称都带有 codex. 前缀。如果某个 metric 包含 tool 字段，它反映的是内部工具名称（例如 apply_patch 或 shell），不包含 codex 正在尝试执行的实际 shell 命令或 patch 内容。

指标	类型	字段	描述
feature.state	counter	feature, value	与默认值不同的 feature 取值（每个非默认值发一行）。
thread.started	counter	is_git	创建新 thread。
thread.fork	counter		通过 fork 现有 thread 创建的新 thread。
thread.rename	counter		thread 重命名。
task.compact	counter	type	按类型（remote 或 local）统计 compaction 次数，含手动和自动。
task.user_shell	counter		用户 shell 动作数量（例如 TUI 中的 !）。
task.review	counter		触发 review 的次数。
task.undo	counter		触发 undo 的次数。
approval.requested	counter	tool, approved	工具审批请求结果（approved、approved_with_amendment、approved_for_session、denied、abort）。
conversation.turn.count	counter		每个 thread 的用户/助手轮次数，在 thread 结束时记录。
turn.e2e_duration_ms	histogram		完整一轮交互的端到端时长。
mcp.call	counter	status	MCP 工具调用结果（ok 或错误字符串）。
model_warning	counter		发送给模型的警告。
tool.call	counter	tool, success	工具调用结果（success 为 true 或 false）。
tool.call.duration_ms	histogram	tool, success	工具执行时长。
remote_models.fetch_update.duration_ms	histogram		获取远端模型定义的时长。
remote_models.load_cache.duration_ms	histogram		加载远端模型缓存的时长。
shell_snapshot	counter	success	获取 shell 快照是否成功。
shell_snapshot.duration_ms	histogram	success	获取 shell 快照所需时间。
db.init	counter	status	State DB 初始化结果（opened、created、open_error、init_error）。
db.backfill	counter	status	初始 state DB 回填结果（upserted、failed）。
db.backfill.duration_ms	histogram	status	初始 state DB 回填时长，并带上 success、failed 或 partial_failure 标签。
db.error	counter	stage	state DB 操作期间的错误（例如 extract_metadata_from_rollout、backfill_sessions、apply_rollout_items）。
db.compare_error	counter	stage, reason	协调一致性时检测到的 state DB 差异。

默认情况下，Codex 允许用户通过 /feedback 发送反馈。要在一台机器上的所有 Codex 界面里禁用反馈收集，请更新配置：

[feedback]
enabled = false

关闭后，/feedback 会显示已禁用消息，Codex 也会拒绝反馈提交。

隐藏或展示 reasoning 事件

如果你想减少嘈杂的 “reasoning” 输出（例如在 CI 日志里），可以抑制它：

hide_agent_reasoning = true

如果你希望在模型发出 raw reasoning 内容时将其展示出来：

show_raw_agent_reasoning = true

只有当你的工作流允许这么做时才启用 raw reasoning。某些模型/provider（例如 gpt-oss）不会发出 raw reasoning；在这种情况下，这个设置不会产生可见效果。

Notifications

使用 notify 可以在 Codex 发出受支持事件时触发一个外部程序（当前只支持 agent-turn-complete）。这适合桌面通知、chat webhook、CI 更新，或任何内建 TUI 通知覆盖不到的旁路告警。

notify = ["python3", "/path/to/notify.py"]

下面是一个会响应 agent-turn-complete 的 notify.py 示例（截断版）：

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

该脚本会接收一个 JSON 参数。常见字段包括：

• type（当前为 agent-turn-complete）
• thread-id（session 标识符）
• turn-id（turn 标识符）
• cwd（工作目录）
• input-messages（导致该轮运行的用户消息）
• last-assistant-message（最后一条助手消息文本）

把脚本放在磁盘上的某个位置，然后让 notify 指向它。

notify 与 tui.notifications

• notify 会运行外部程序（适合 webhooks、桌面通知器、CI hooks）。
• tui.notifications 内建在 TUI 中，并且可按事件类型过滤（例如 agent-turn-complete 与 approval-requested）。
• tui.notification_method 控制 TUI 如何发出终端通知（auto、osc9 或 bel）。

在 auto 模式下，Codex 会优先使用 OSC 9 通知（某些终端会把它解释为桌面通知的终端转义序列），否则回退到 BEL（\x07）。

准确配置键请参见 Configuration Reference。

历史持久化

默认情况下，Codex 会把本地 session transcripts 保存到 CODEX_HOME 下（例如 ~/.codex/history.jsonl）。如果想禁用本地历史持久化：

[history]
persistence = "none"

如果想限制 history 文件大小，请设置 history.max_bytes。当文件超过上限时，Codex 会丢弃最旧的条目，并在保留最新记录的同时压缩该文件。

[history]
max_bytes = 104857600 # 100 MiB

可点击引用

如果你使用支持它的终端/编辑器集成，Codex 可以把文件引用渲染为可点击链接。配置 file_opener 来选择 Codex 使用的 URI scheme：

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

例如，像 /home/user/project/main.py:42 这样的引用可以被重写成可点击的 vscode://file/...:42 链接。

项目说明发现

Codex 会读取 AGENTS.md（以及相关文件），并在 session 首轮中包含一部分受限长度的项目指导。下面两个旋钮控制这个过程：

• project_doc_max_bytes：每个 AGENTS.md 文件最多读取多少字节
• project_doc_fallback_filenames：当某个目录层级缺少 AGENTS.md 时，额外尝试哪些文件名

关于完整机制，请参见 Custom instructions with AGENTS.md。

TUI 选项

在不带子命令运行 codex 时，会启动交互式终端 UI（TUI）。Codex 在 [tui] 下暴露了一些 TUI 专属配置，包括：

• tui.notifications：启用/禁用通知（或只允许特定类型）
• tui.notification_method：选择 auto、osc9 或 bel 作为终端通知方式
• tui.animations：启用/禁用 ASCII 动画和 shimmer 效果
• tui.alternate_screen：控制是否使用 alternate screen（设为 never 可保留终端滚动历史）
• tui.show_tooltips：显示或隐藏欢迎页上的 onboarding tooltips

tui.notification_method 的默认值是 auto。在 auto 模式下，如果终端看起来支持，Codex 会优先使用 OSC 9 通知（某些终端会把它解释为桌面通知的终端转义序列）；否则回退到 BEL（\x07）。

完整键列表请参见 Configuration Reference。